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This manual provides detailed informa- 
tion on catalog management routines. These 
routines record identification of volumes 
used by data sets by maintaining informa- 
tion in logical records called indexes. 
The functions and structures of the rou- 
tines are described, as are their relation- 
ships to other portions of IBM System/360 
Operating System. This manual also des- 
cribes the structure of catalog data sets 
that contain the indexes processed by 
catalog management routines. It is intend- 
ed for use by persons involved in program 
maintenance, and system programmers who are 
altering the program design. Program logic 
information is not necessary for the use 
and operation of the program; therefore, 
distribution of this publication is limited 
to those with the aforementioned require- 
ments . 
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PREFACE 



The information contained in this manual 
is intended for programmers engaged in 
maintenance of catalog management routines. 
Because of the close relationship between 
catalog management and other portions of 
the control programs of IBM System/360 
Operating System, many details in this 
manual are helpful in understanding overall 
system operations. 

This manual is arranged in two sections. 
The first describes the structure of a 
catalog data set and how indexes and volume 
control blocks are recorded in such a data 
set. The second is the description of the 
catalog management functions and the inter- 
nal logic of the routines that perform the 
functions. 

The manual is a detailed and comprehen- 
sive guide to the internal structure and 
functions of the catalog management rou- 
tines. It is designed to be used in 
conjunction with assembly listing and, con- 
sequently, does not discuss program struc- 
ture at the machine instruction level. 
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INTRODUCTION 



The system for identifying the volumes 
on which data sets are recorded consists of 
two parts: the catalog and the catalog 
management routines. The catalog is one or 
more data sets each of which is recorded on 
a separate direct-access volume. The 
catalog contains the information necessary 
to identify the volumes on which other data 
sets reside. Catalog management routines 
provide access to the catalog and update 
the catalog as necessary. 



tion data groups. They allow the automatic 
cataloging functions provided for genera- 
tion data groups as described in the publi- 
cation IBM System/36 Operating System; 
Data Management . Normal indexes facilitate 
data separation among several functions or 
departments by providing names that are 
used to qualify simple data set names. For 
example, two departments, A and B, can 
create two indexes named A and B, respec- 
tively. Both departments can give the name 
DATA to one of their data sets and refer to 
it without ambiguity by using their indexes 
as qualifying names (i.e., A. DATA, and 
B.DATA). 



THE CATALOG 



A direct-access volume that contains a 
catalog data set is called a control vol- 
ume. In any operating system, the system 
residence volume is always a control volume 
because a catalog data set is created on it 
at system generation time. Each catalog 
data set is named SYSCTLG. One such data 
set can serve as the catalog of an operat- 
ing system. If there is more than one 
catalog data set in an operating system, 
each data set can be separate and distinct, 
or several data sets can be logically 
connected. 



Catalog data sets contain two types of 
unit: indexes and volume control blocks. 
Both are variable- length records recorded 
in one or more fixed- length blocks. An 
index is a series of variable-length 
entries that identify other indexes,, con- 
trol volumes, or volumes of data sets by 
name and physical location. A volume con- 
trol block contains volume identification 
for a data set when the data set extends 
over more volumes (five) than can be easily 
identified in an index. Volume control 
blocks, therefore, supplement information 
in indexes and are identified by entries in 
indexes. 



There are three types of index: the 
volume index, the generation index, and the 
normal index. Every control volume is 
initialized by catalog management routines 
with a basic index structure called the 
volume index. This is all the structure 
that is required to catalog data sets with 
simple names. Generation indexes contain 
the identification of data sets of genera- 



CATALOG MANAGEMENT ROUTINES 



The catalog management routines provide 
the functions for the LOCATE, INDEX, and 
CATALOG macro-instructions described in the 
publication IBM System/3 60 Operating Sys- 
tem; System Programmer's Notebook , Form 
C28-6550. For the locate function, catalog 
management finds volume information of a 
cataloged data set by searching the index 
structure for the qualified name of the 
data set. It can also read an index block, 
if provided with the address of the block. 
For the index function, catalog management 
inserts or deletes indexes in a catalog 
data set. For the catalog function, catal- 
og management can enter or delete the 
identification of the volumes of a data 
set. 



Components of the operating system use 
the catalog management routines when catal- 
oging operations are requested in data 
definition (DD) statements of the job con- 
trol language. Utility programs also use 
catalog management routines to build a 
catalog in an operating system. The locate 
function of catalog management is used by 
job management to find a cataloged data set 
when the data set is requested as input to 
a program. The locate operation includes 
calculation of new generation numbers of 
generation data sets. The catalog function 
is used by job management to catalog a data 
set after it has been created. The index 
function of catalog management is used by 
utility programs to build indexes in a 
catalog data set. 



Introduction 



CATALOG STRUCTURE 



An index is a record of indefinite 
length consisting of a series of fields or 
entries. The record is open-ended to 
accominodate new entries. The entries are 
in ascending sequence of the binary value 
of their name fields, and they are contigu- 
ous to one another at the beginning of the 
index. 



To be recorded on a direct-access vol- 
ume,, the records are divided into fixed- 
length blocks. Each block consists of an 
eight-byte key and a 256-byte data portion. 
Index entries are placed in the data 
portion of the block, and the key is used 
to identify the block. An index may extend 
over several blocks, but two indexes can 
not share a block- Blocks of an index are 
chained together in the proper sequence by 
addresses at the end of each block. When 
processing an index, the catalog management 
routines begin with the first block of the 
index and, through chain addresses, contin- 
ue to the last block. 



The first field in the data portion of 
an index block is two bytes long and 
contains the count of the number of used 
bytes in the data portion. That field is 
necessary because the lengths of index 
entries vary, and an index block will not 
always be filled (i.e., there may be unused 
bytes at the end of the block' s data 
portion) . Index entries are placed in the 
data portion following the byte count 
field. 



Each entry in an index is either a 
control entry or a pointer entry. Control 
entries contain information about the index 
in which they appear, such as the address 
of the first and last blocks assigned to 
the index or the chain address to the next 
block. Pointer entries contain the names 
of other index levels and the identifi- 
cation of the entity (index address, con- 
trol volume, volumes of a data set, or a 
volume control block) to which each name 
applies. 



The first entry in the first block of an 
index is a control entry. The entry indi- 
cates the address of the last block of the 
index and the number of unused bytes at the 
end of that block. The special control 
entry at the beginning of the volume index 
indicates the first available block in the 
catalog data set not assigned to any index. 



The last entry in an index block is usually 
a control entry that contains the address 
(the chain address) of the next block in 
the index. If two blocks are adjacent and 
if the blocks are in the proper logical 
sequence in an index, the control entry can 
be eliminated from the end of the first of 
the two blocks. Pointer entries are placed 
in the data portion of an index block 
following the control entry at the begin- 
ning of the index and up to the control 
entry at the end of each block. The last 
entry in the last block of any index is a 
control entry with a chain address of zero. 



The key of each block contains the name 
that appears in the last entry (control or 
pointer) in the data portion of the block. 
Since entries are placed in the index in 
ascending sequence of their name values, 
the name in the key will always be the one 
of highest binary value in the block. 

A volume control block, like an index, 
is recorded in one or more blocks with 
8-byte keys and 256-byte data portions. If 
a volume control block extends over more 
than one block, the blocks are chained 
together. One block of a volume contro] 
block contains up to" 20 volume serial 
numbers for one data set. The key of each 
block contains the hexadecimal number FF. 

Figure 1 shows a method of chaining 
blocks that provides ease of access to 
catalog entries. Blocks A, B., C, D, and E 
are all of one index. The entries are 
placed in the index in the sequence of the 
binary value of the name fields of the 
entries, from name A to name Z. The key of 
each block contains the eight-byte name 
that is the last entry in the data portion 
of the block. 

Blocks A, B, and C are contiguous. The 
last entry in block C is an index link 
entry that indicates block D as the next 
block of the index. Blocks C and D are 
separated by blocks of another index or by 
volume control blocks, and the name in the 
key of block C is, therefore, hexadecimal 
FF. Blocks D and E are contiguous, and the 
last entry in block E is the index link 
entry indicating that no block follows 
block E. The name in the key of block E is 
hexadecimal FF, and the address in the last 
entry of block E is zero. This system of 
recording indexes allows the catalog man- 
agement routines to use a channel program 
to search the keys for a name greater than 
or equal to a name to be found. 
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Figure 1. Catalog Index Chaining 



Except for the first volume index block, 
index blocks or blocks of volume control 
blocks have no assigned position in a 
catalog data set. Blocks of the same index 
or volume control block are not necessarily 
contiguous; they may be chained together. 
The address of the first available block in 
a catalog data set is recorded in its 
volxime index. When an index or volume 
control block overflows, the first availa- 
ble block is assigned to that index or 
volume control block. When an index or 
volume control block is reduced so that one 
of its blocks becomes empty, binary zeros 
are written in the empty block's key, and 
the block is returned to the pool of 
available blocks. If the block is closer 
to the beginning of the data set than any 
other available block, it is the first to 
be used when an index overflows or when a 
block is needed to record a volume control 
block. Thus, unused blocks will tend to 
accumulate close to the end of the data 
set. 



INDEX CONTENTS 



An index contains one or more variable- 
length entries of which there are two 



types: control and pointer. Control 
entries identify the beginning and end of 
each index and the end of each block. 
Control entries are used to chain blocks of 
the same index. Pointer entries identify 
one of the following: 



Another index. 

A data set's volumes. 

A volume control block. 

A control volume. 

A generation index. 

An alias of an index. 



All indexes do not contain all types of 
pointer entries. Normal indexes can not 
contain entries that identify control 
volumes or aliases of indexes. Generation 
indexes can contain only those entries that 
identify data set volumes or volume control 
blocks. Volume indexes can contain any 
type of pointer entry. Names appearing in 
entries in volume indexes are called high 
level names, and indexes identified by such 
entries are called high level indexes. 
Table 1 is a graphic summary of all the 
entries. The entries are described in the 
following paragraphs. 



Catalog Structure 



Table 1. Suinmary of Index Entry Formats 
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Volume Control Block Pointer Entry 
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CONTROL ENTRIES 



A volume index control entry is 



the first entry 
consists of the 
volume index, the 
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fields. 



always 

volume index- It 
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m a 
ending 

amount of available space 

ex, and the address of the 
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Field 1; Name Field (8 bytes long) — This 
field contains the binary number one to 
ensure that the entry will appear as the 
first entry in the first block of the 
index. 



Field 2; Last Block Address (3 bytes long) 
— This field contains the relative track 
address of the last block in the volume 
index. The address is in the form TTR, 
where TT is the track address and R is the 
block address. 



Field 3; Half-word Count (1 byte long) — 
This field contains the binary number five 
to indicate that five half-words follow 



this field in this entry. 



Field 4; Catalog Upper Limit (3 bytes 
long) -- This field contains the relative 
track address of the last block in the 
catalog data set. The address is in the 
form TTR. 

Field 5; Zero Field (1 byte long) — This 
field contains binary zeros. 

Field 6 ; First Available Block Address (3 
bytes long) — This field contains the 
relative track address of the unused block 
in the catalog that is closest to the 
beginning of the catalog data set. 



ensure that this entry will be the first 
entry in the first block of the index 
because it has the lowest binary name 
value. 



Field 2; Last Block Address (3 bytes long) 
— This field contains the relative track 
address of the last block assigned to the 
index. The address is in the form TTR. 



Field 3; Half-word Count (1 byte long) 
This field contains the binary number three 
to indicate that three half-words follow 
this field in this entry. 



Field 4; Index Lower Limit (3 bytes long) 
This field contains the relative track 
address of the block in which this entry 
appears. The address is in the form TTR. 



Field 5: Number of Aliases (1 byte long) 
— This field contains the binary count of 
the number of aliases to this index. If 
this index is not a high level index, this 
field must be zero. 



Field 6: Unused Bytes in Last Block (2 
bytes long) — This field contains the 
binary count of the number of unused bytes 
remaining in the last block in the index. 

An index link entry is the last entry in 
either the last block of an index or any 
block not physically contiguous to the next 
block of the same index. When the entry is 
in the last block of the index, it contains 
the hexadecimal number FF and an address 
field of zeros. When the entry is in a 
block that is not physically contiguous to 
the next block of the index, it contains 
the hexadecimal number FF and the address 
of the next block of the index. The entry 
is 12 bytes long and contains 3 fields. 



Field 7 ; Zero Field (1 byte long) — This Field 1; Name Field (8 bytes long) — This 

field contains the hexadecimal number FF. 
That number ensures that this entry will 



field contains binary zeros, 



Field 8; Unused Bytes in Last Block (2 
bytes long) — This field contains the 
binary count of the number of unused bytes 
in the last block of the volume index. 

An index control entry is always the 
first entry in any index except in volume 
indexes. It indicates the amount of Space 
available in the last block of the index, 
and the addresses of the first and last 
blocks assigned to the index. The entry is 
18 bytes long and contains 6 fields. 

Field 1; Name Field (8 bytes long) — This 
field contains the binary number one to 



appear as the last entry in any index block 
because it has the highest name value. 



Field 2: Link Address (3 bytes long) — 
This field contains the relative track 
address of the next block in the same 
index, if there is a next block in the 
index. Otherwise, the field contains 
binary zeros. 

Field 3; Half-word Count (1 byte long) — 
This field contains the binary number zero 
to indicate that this field is followed by 
no fields in this entry. 



Catalog Structure 



POINTER ENTRIES 



An index pointer entry can appear in all 
indexes except generation indexes. It con- 
tains the name of an index in the same 
SYSCTLG data set and the relative address 
of the first block of that index. The 
entry is 12 bytes long and contains 3 
fields. 

Field 1: Name Field (8 bytes long) — This 
field contains the name of the index being 
pointed to by field 2. 

Field 2: Index Address (3 bytes long) — 
This field contains the relative track 
address of the first block of the index 
named in fi^ld 1. The address is in the 
form TTR. 

Field 3: Half-word Count (1 byte long) — 
This field contains the binary number zero 
to indicate that no fields follow this 
field in this entry. 

A data set pointer entry can appear in 
any index. It contains the simple name of 
a data set and from one to five 12- byte 
fields that each identify one volume on 
which the named data set resides. If the 
data set pointer entry appears in a genera- 
tion index, the generation number and ver- 
sion number together form the simple name 
of the data set in the entry. The genera- 
tion, but not the version number, of the 
data set in the entry is the ones comple- 
ment of the true generation number. If the 
data set resides on more than five volumes, 
a volume control block must be used to 
point to the data set's volumes. The 
volume control block is identified by a 
volume control block pointer entry, not a 
data set pointer entry. 

The data set pointer entry is variable- 
length. The length is determined by the 
formula (lU+12m), where m is the number of 
volumes containing the data set. The 
variable m can be from 1 through 5. The 
entry can appear in any index, and it 
contains 5 fields. 

Field 1: Name Field (8 bytes long) — This 
field contains the simple name of the data 
set whose volumes are identified in field 5 
of this entry. The simple name of a 
generation data set consists of the ones 
complement of the data set's true genera- 
tion number followed by the true version 
number. 

Field 2: Address Field (3 bytes long) 
This field contains the binary number zero. 



Field 



Half-word Count (1 byte long) 



This field contains the binary count of the 
number of half-words that follow this field 



in this entry. The number is found by the 
formula (6m+l) , where m is the number of 
volumes upon which the data set resides. 
The variable m can be from 1 through 5. 

Field U; Volume Count (2 bytes long) — 
This field contains the binary count of the 
number of volumes identified in field 5 of 
this entry. 

Field 5; Volume Entries (12 to 60 bytes 
long, one to five entries) -- This field 
contains from one to five 12-byte entries. 
Each entry contains the device code, serial 
number and sequence number of one volume 
containing the data set named in field 1. 
The device code is 4 bytes long, the volume 
serial number is 6 bytes long, and the 
sequence number is 2 bytes long. The 
sequence number indicates the position of 
the data set on a tape volume. The 
sequence number is zero for direct-access 
volumes. 

A volume control block pointer entry can 
appear in any index. It contains the 
simple name of the data set and the address 
of the first or only physical block of the 
volume control block for the data set. The 
volume control block can identify up to 20 
volumes. When this entry appears in a 
generation index, the generation number and 
version number together form the simple 
name of the data set. The generation, but 
not the version number, is the ones comple- 
ment of the actual EBCDIC coded generation 
number. The entry is 14 bytes long and 
contains 4 fields. 

Field 1; Name Field (8 bytes long) — This 
field contains the simple name of the data 
set identified by this entry. The data set 
resides on the volumes whose serial numbers 
are given in the volume control block 
pointed to by field 2. 

Field 2; Address Field (3 bytes long) 
This field contains the relative track 
address of the volume control block iden- 
tifying the volumes containing the data set 
named in field 1. The address is in the 
form TTR. 

Field 3: Half-word Count (1 byte long) — 
This field contains the binary number one 
to indicate that one half-word follows this 
field in this entry. 

Field 4; Zero Field (2 bytes long) — This 
field contains binary zeros. 

A control volxame pointer entry can 
appear only in volume indexes. It contains 
the name of a high level index name in the 
volume index on another control volume. It 
is used in installations whose catalogs 
extend over several volumes. A control 
volume pointer entry in one catalog data 
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set directs catalog searches from one con- 
trol volume to another that contains the 
desired index. (A high level index is one 
that is identified by an entry in a volume 
index. The name of a high level index can 
have no qualifiers.) It also contains the 
serial number of the control volume con- 
taining that volume index. The entry is 18 
bytes long and contains U fields. 



Field 1; Name Field (8 bytes long) — This 
field contains a high level name that 
appears in the volume index of the control 
volume identified in field 4. 



Field 2 



Address Field (3 bytes long) — 



This field contains binary zeros. 

Field 3; Half-word Count (1 byte long) 
This field contains the binary number three 
to indicate that three half-words follow 
this field in this entry. 

Field U; Control Volume Serial Number (6 
bytes long) — This field contains the 
volume serial number of the control volume 
whose volume index contains an entry iden- 
tifying the high level name in field 1. 

An alias entry can appear in volume 
indexes only. It contains an alias given 
to an index, the address of the index, and 
the true name of the index. An alias can 
be given only to indexes, and only if they 
are high level indexes. An alias entry is 
20 bytes long and contains 4 fields. 



Field 1: Name Field (8 bytes long) — This 
field contains the name of the generation 
index whose address is given in field 2. 

Field 2; Address Field (3 bytes long) 
This field contains the relative track 
address of the generation index named in 
field 1. The address is in the form TTR. 

Field 3; Half-word Count (1 byte long) -- 
This field contains the binary number two 
to indicate that two half-words follow this 
field in this entry. 

Field 4: Flags (1 byte long) — This field 
contains flags that govern the uncataloging 
of data sets from the index as specified by 
the DELETE or EMPTY options of the INDEX 
macro that were used when the generation 
index was created. The options and their 
hexadecimal codes are as follows: 

EMPTY=01 DELETE=0 2 EMPTY and DELETE=0 3 

Field 5; Maximum Generations Allowed (1 
byte long) — This field contains the 
binary count of the maximiim number of 
generations allowed in the index at one 
time as specified in the INDEX macro when 
the index was created. 

Field 6; Current Generation Count (2 bytes 
long) — This field contains the binary 
count of the number of generations cata- 
loged in the index. 



THE VOLUME CONTROL BLOCK CONTENTS 



Field 1: Name Field (8 bytes long) — This 
field contains the alias of the high level 
index identified in field 2. 

Field 2 ; Address Field (3 bytes long) — 
This field contains the relative track 
address of the first block of the index 
named in field 4. The address is in the 
form TTR. 

Field 3 : Half-word Count (1 byte long) -- 
This field contains the binary number four 
to indicate that four half-words follow 
this field in this entry. 

Field 4; True Name Field (8 bytes long) — 
This field contains the name of the index 
to which was given the alias name that 
appears in field 1. The address of the 
index is in field 2. 

A generation index pointer entry can 
appear in all indexes except generation 
indexes. It contains the name of a genera- 
tion index, the address of the first block 
of the index, and control information about 
the generation data group identified in the 
index. The entry is 16 bytes long and 
contains 6 fields. 



The format of a volume control block is 
always the same. Each block of a volume 
control block contains up to twenty volume 
serial numbers for one data set. Each 
block is 256 bytes long and contains five 
fields. The fields are described in the 
following paragraphs. 

Field 1; Number of Volumes (2 bytes long) 
— This field contains the binary count of 
the number of volume serial numbers con- 
tained in this physical block and in all 
subsequent blocks chained to this block. 
If a data set is on 61 volumes, for 
example, it will have four volume control 
blocks. The first fields of those blocks 
will contain 61,41,21, and 1, respectively. 



Field 



long) - 

entries 

identif 

giving 

number, 

device 

number 

number 

number 



2: Volume Serial Numbers (240 bytes 

This field contains up to 20 

of 12 bytes each. Each entry 

ies one volume of the data set by 
the volume's device code, serial 
and data set sequence number. The 
code is 4 bytes long, the serial 

is 6 bytes long, and the sequence 
is 2 bytes long. The sequence 

is zero for direct-access volumes. 
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Field 3: Zero Field (10 bytes long) -- volume identification for the following 

This field contains binary zeros. data sets: 

Field 4; Chain Address (3 bytes long) — 

This field contains the relative track Q 

address of the next block of this volume A.B.jyKalias B.B.M) 

control block, if additional blocks exist. D.B 

The address is in the form TTR. If no next E 

block exists, the field contains binary A.J (alias B.J) 

zeros. If this field is not zero, this A. G (alias B.G) 

block must contain twenty 12-byte fields D.C 

identifying volumes of the data set. D.A. B 

A.B.K(alias B.B.K) 

Field 5; Zero Field (1 byte long) — This A.B.N(alias B.B.N) 

field contains binary zeros. D.A.C 

It also identifies the following genera- 

A SAMPLE CATALOG tion data sets: 

F(0) 

Figure 2 shows a sample catalog that F(-3) 

consists of two catalog data sets: one on F(-l) 

the system residence volume and the other D.A.D(O) 

on a control volume. The catalog contains F(-2) 
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Figure 2 . A Sample Catalog 
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CATALOG MANAGEMENT ROUTINES 



There are two catalog management rou- 
tines: the catalog routine and the CVOL 
routine. The catalog routine provides the 
catalog,, index, and locate functions. In 
providing the locate function, catalog man- 
agement finds entries in the catalog by 
searching indexes specified in a qualified 
data set name. For the catalog function, 
catalog management inserts, deletes, or 
replaces data set pointer entries, volume- 
control block pointer entries^, and volume 
control blocks. For the index function, 
catalog management enters into and deletes 
from the catalog the indexes, generation 



index pointer entries, index pointer 
entries, control volume pointer entries, 
and alias entries. The CVOL routine pro- 
vides services to the catalog routine by 
opening catalog data sets for processing 
and by writing format blocks in new catalog 
data sets. The catalog routine consists of 
five modules: IGC0002F, IGG0CLC2, IGG0CLC3, 
IGG0CLC4, and IGG0CLC5. (See Figure 3.) 
The CVOL routine consists of two modules: 
IGC0002H and IGG0CLF2. (See Figure 4.) 
Each module is loaded separately into the 
transient area of main storage and is 
executed in the supervisor mode. 
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Figure 3. The Catalog Routine Modules 
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Figure 4. CVOL Routine Modules 



THE LOCATE FUNCTION (MODULES IGC0002F AND 
IGG0CLC4) 



In performing the locate function, the 
catalog routine finds entries in catalog 
data sets. The function is performed by 
modules IGC0002F and IGG0CLC4 of the catal- 
og routine. Entry to the routine is made 
in module IGC0002F. The calling routine 
provides a qualified name (such as A-B-C), 
the function to be performed, and possibly 
identification of a control volume. Module 
IGC00 02F searches for the named entry 
beginning at the volume index of the system 
residence volume, unless a control volijme 
was specified in the input. 

The search proceeds through each index 
level in the qualified name until all 
levels are found or until one of the named 
levels can not be found. If module 
IGC0002F encounters a generation index, 
control passes to module IGG0CLC4 to find 
the last level of the name- 

When an index is being searched for a 
named entry, a channel program is con- 
structed, and searches the keys for a name 
that is equal to or greater than the given 
name. Contiguous blocks of the index are 
searched by the channel program automat- 
ically. But the search program must termi- 
nate at a block that is not contiguous to 
the next block of the index. The termina- 
tion is caused by the fact that the key 
name of a block not contiguous to the next 
is hexadecimal FF, a value greater than any 
name in an index. The search program can 
then be reinitiated at the next block of 
the index- 



In Figure 1, for example, the locate 
function might be requested to find the 
item named F. A channel program would 
compare F to the key name of block A. 
Since E is less than F, the channel program 
would proceed to the next contiguous block. 
The key of that block would be compared to 
F. Since K is greater than F, the channel 
program would read in block B which con- 
tains, or should contain, the item named F. 



When searching the index for the item 
named R, the channel program would compare 
the key names of the blocks A,B, and C to 
the name R. Since the key name in block C 
is greater than R, the channel program 
would read in block C. A comparision would 
then be made between the name R and the 
name in the next to the last entry in block 
C. Since that name, P, is not equal to or 
greater than R, catalog management would 
process the next block of the index at the 
address indicated in the last entry of 
block C. If the address in the last entry 
is zero, the search terminates because it 
has reached the end of the index. 

When the locate search terminates, the 
module in control indicates the outcome of 
the search with an error code placed in a 
general register. The code indicates 
whether all levels were found, why the 
search failed, if it did, and what type of 
entry was the last found. 

Module IGC0 002F reads information from 
the catalog and passes it to the calling 
routine. The information passed depends on 
the kind of entry found. If the last entry 
found is a volume control block pointer 
er^try, the entry and the control block are 
read from the catalog data set. If the 
entry is a data set pointer entry, the 
volume information from the entry is placed 
in the work area. If the last entry found 
is a normal or generation index pointer 
entry, the pointer entry and the first 
block of the index pointed to are placed in 
the work area. 

Module IGC0 002F always returns to the 
calling routine with the true name of the 
catalog entry that was located. For exam- 
ple, if S is an alias of TRUE in the 
catalog, and if the module finds S.T. U, the 
true name TRUE.T.U is returned by the 
locate function. 

In addition to finding a named entry in 
the catalog, module IGC0002F reads any 
block in a catalog data set when the 
calling routine provides a relative track 
address instead of an entry name. A rela- 
tive track address is supplied by a pre- 
vious locate operation and is used to 
locate the second and subsequent blocks of 
an index. Only one block is read at one 
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time, and it is placed in the work area 
specified by the calling routine. 

Module IGG0CLC4 must provide special 
operations to find an entry in a generation 
index. Generations of a group are indicat- 
ed by the calling routine in one of two 
ways: by generation and version number 
(X. Y. Z.GnnnVmm) or by relative qualifier 
(X. Y.Z(-3)). When the data set name pro- 
vided to the locate function contains the 
generation and version number, the module 
IGG0CLC4 must complement the generation 
number and search the proper generation 
index for the named entry. The volume 
identification provided by the entry is 
placed in the work area. 

To find an entry specified by a relative 
qualifier, module IGGOCLCU determines the 
required generation by the relative posi- 
tion of the generation's entry in the 
index. If the relative qualifier is zero, 
the latest generation is needed, and module 
IGG0CLC4 provides the information from the 
first entry in the index. If the relative 
qualifier is negative, the module finds the 
generation index entry that is the speci- 
fied number of entries from the first in 
the index. If the relative qualifier were 
-2, for example, the module would find the 
generation index entry that was the third 
in the index. 

If the relative qualifier were positive, 
indicating a new generation, module 
IGG0CLC4 would find the latest entry in the 
generation data group (first in the index) 
and would calculate the generation and 
version number of the new generation data 
set. The new generation and version num- 
bers are found by the formulas: 

(new generation) = (latest generation 

number) + (relative qualifier) 
(version number) = 00 

Whenever a relative qualifier is used,, 
module IGG0CLC4 returns the corresponding 
absolute name of the generation. For exam- 
ple, if generation index A.B.C contained 
the latest generation numbered 25, and if 
module IGG0CLC4 were given the name 
A.B.C(O), the routine would return with the 
name A.B.C. G0025V00. If the module were 
given A.B.C(+3), the routine would return 
with the name A.B.C.G0028V00. 



THE INDEX FUNCTION (MODULES IGC0002F, 
IGG0CLC2, AND IGG0CLC3) 



In performing the index function, the 
catalog routine places into and removes 
from a catalog, indexes, aliases, and con- 
trol volume pointer entries as well as the 



items those entries identify. The index 
function is performed by modules IGC0002F, 
IGG0CLC2, and IGG0CLC3. Entry to the rou- 
tine is in module IGC0002F; the same entry 
point as that of the locate function. The 
calling routine specifies a name of an 
index, the option to be provided by the 
function, and possibly a control volume 
serial number. Other parameters must be 
supplied depending on the option requested. 
For example, if the routine is to create an 
alias entry, an alias name must be provided 
by the calling routine. 



Module IGC0002F 
tion as the firs 
tion. The locate 
searching the cata 
in the input, 
search, a general 
outcome of the 
contains the last 
locate operation. 



performs a locate opera- 
t step in the index func- 
operation consists of 
log for the name provided 
At the completion of the 

register indicates the 
search, and the work area 
entry found, as in any 



Module IGC0002F passes control to module 
IGG0CLC2. Module IGG0CLC2 interrogates the 
general register set by the locate opera- 
tion to determine whether the requested 
index operation can be performed with the 
existing catalog. If the operation can not 
be performed, control returns to the caller 
with an indication of the error encoun- 
tered. Otherwise, module IGG0CLC2 creates 
any new pointer entries and index blocks or 
sets an indication of what entry and index 
are to be deleted. Control passes to 
module IGG0CLC3. 

Module IGG0CLC3 updates the index indi- 
cated by module IGG0CLC2. The updating of 
an index includes processing of the index 
to maintain ascending sequence of entry 
names and to eliminate "holes" created by 
deletion of entries. Updating also 
includes the assignment or release of index 
blocks when indexes are created or extend- 
ed, or deleted or emptied. 



THE CATALOG FUNCTION (MODULES IGC0002F, 
IGG0CLC2, IGG0CLC3, IGGOCLCU, AND IGG0CLC5) 



In performing the catalog function, the 
catalog routine inserts into and deletes 
from a catalog index the data set pointer 
entries and volume control blocks and their 
pointer entries. Before a data set is 
cataloged, the indexes used by the catalog 
function must exist. The catalog function 
provides the CATALOG, UNCATALOG, and RECA- 
TALOG options and is performed by modules 
IGC0002F, IGG0CLC2, IGG0CLC3, IGG0CLC4, and 
IGG0CLC5. The sequence of module execution 
depends on whether the index to be updated 
is a normal (or volume) index or a genera- 
tion index. Generation data sets are cata- 
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loged by modules IGC0002F, IGGOCLCU, 

IGG0CLC5, and IGG0CLC3. Other data sets 

are cataloged by modules IGG0002F, 
IGG0CLC2, and IGG0CLC3. 



Entry to the catalog routine for the 
catalog function is in module IGC0002F. 
The calling routine must provide the name 
of the data set, the list of the data set's 
volume serial numbers, the option to be 
provided, device type, data set sequence 
number, and possibly a control volume seri- 
al number. Module IGC0002F locates the 
name of the data set by searching the 
catalog as in a normal locate operation. 
The module passes control to module 
IGG0CLC4 if a generation index is found. 
Otherwise, the outcome of the search is 
indicated in a general register and the 
entry and index found are placed in a work 
area, and control passes to module 
IGG0CLC2. 

Module IGG0CLC2 interrogates the general 
register to determine if the requested 
function can be performed in the existing 
catalog. If not, control passes to the 
calling routine with an error indication. 
Otherwise, a new data set pointer entry or 
volume control block pointer entry is 
created by module IGG0CLC2 if cataloging 
was requested. If a volume control block 
is required, it is created by the module. 
If uncataloging was requested, module 
IGG0CLC2 sets an indication of what entry 
is to be deleted from the catalog. If 
recataloging was specified,, module IGG0CLC2 
creates the new entry and indicates what it 
is to replace in the catalog. Control then 
passes to module IGG0CLC3. 

Module IGG0CLC3 updates the index as 
indicated by module IGG0CLC2. During the 
updating, the ascending sequence of entry 
names in the index must be maintained, and 
"holes" created by deletion of entries must 
be eliminated. Index processing also 
includes the assignment or release of index 
blocks when index blocks are emptied, when 
indexes are extended, or when volume con- 
trol blocks are created or deleted,. 

When generation data sets are being 
cataloged, the catalog routine must be 
given the name of the data set with the 
generation and version numbers in the form 
GnnnnVmm. Modules IGG0002F and IGGOCLCU 
find the generation index that is to 
receive the new entry and determine that 
the name of the new generation is not a 
duplicate of a name in the index. Module 
IGG0CLC5 creates any new index entries and 
volume control blocks, and module IGG0CLC3 
places the new entries and blocks in the 
catalog or deletes entries and blocks as 
specified. Automatic recataloging of a 
data set occurs when duplicate generation 



numbers are found (version numbers are 
ignored) . 

When cataloging generation data sets, 
the catalog function may uncatalog a data 
set from the generation index. The unca- 
taloging is specified by the generation 
index control entry that contains a number 
indicating the maximum number of entries 
allowed in the index at one time. The 
number is supplied by the user when the 
index is created. If a data set is unca- 
taloged and the DELETE option was specified 
when the index was created, the catalog 
function calls the scratch routine of DADSM 
to scratch the data set. If the EMPTY 
option was specified and the index contains 
the maximum number of entries allowed by 
the user, cataloging of a new generation 
causes all existing entries to be removed 
from the index. Control passes from module 
IGG0CLC5 to module IGG0CLC4 if the EMPTY 
option was specified and the index over- 
flows. Module IGGOCLCU then creates a new 
generation number for the new pointer entry 
calculated on the basis of the empty gener- 
ation index. 



THE CVOL ROUTINE 



The CVOL routine performs services for 
the catalog routine: it opens and extends 
catalog data sets, and writes format blocks 
in catalog data sets and in directories of 
partitioned data sets. 

The open function is similar to the open 
function of data management. Before the 
catalog routine can process a catalog data 
set, the CVOL routine must find the DSCB of 
the data set and complete a DCB and DEB 
with extent descriptions from the DSCB. If 
a catalog data set has never been processed 
by catalog management, the CVOL routine 
writes format blocks in the data set at the 
same time that it opens it. When a catalog 
data set overflows its boundaries, the 
catalog routine requests the CVOL routine 
to allocate additional space to the data 
set and write format blocks in that space. 
The CVOL routine calls the extend routine 
of DADSM to allocate additional space and 
update the data set's DSCB. 



THE CVOL ROOTINE MODULES (MODULES IGC0002H 
AND IGG0CLF2) 



The CVOL routine consists of two separ- 
ate modules that are loaded into the tran- 
sient area of main storage at different 
times. As shown in Figure U, module 
IGC0002H opens control voliime catalog data 
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sets by creating a DCB and DEB from infor- index in the first block of the data set 
mation in the data set DSCB. This module and places a volume index control entry at 
also calls the extend routine of DADSM to the beginning of the index. When process- 
extend a catalog data set. Module IGG0CLF2 ing a partitioned data set directory, the 
writes format blocks in catalog data sets module writes format blocks and places a 
with 256-byte data portions and 8-byte special entry in the first block of the 
keys. The module also constructs a volume directory. 
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